[Chapter 38] 38.7 Add Debugging for Detail
Author: Bryan Costales & Eric Allman
Date: 1999-01-06T22:49:42Z

#

| Chapter 38 Rule-Set Testing with -bt |

## 38.7 Add Debugging for Detail

In rule-testing mode the `-d` rule-testing command can be used to turn debugging output on and off. Prior to V8.7 sendmail the `-d` could be specified only on the command line. Beginning with V8.7 sendmail, the `-d` may also be specified in rule-testing mode. We illustrate the latter technique here.

Debugging output can reveal in great detail how individual rules are being handled. A debugging category and level of `21.12`, for example, causes sendmail to print the LHS of each rule as it is tried. To illustrate, consider the following (highly simplified) configuration-file rule set:

>     S0
>     R@                  $#local $:$n                 handle <> form
>     R$*<@$+>$*          $#$M $@$R $:$1<@$2>$3        user@some.where
>     R$+                 $#local $:$1                 local names

Normal output that is produced when a rule-set number and address are entered at the `>` prompt looks like this:

>     > 0 george
>     rewrite: ruleset   0   input: george
>     rewrite: ruleset   0 returns: $# local $: george

But if we turn on debugging using the `-d` rule-testing command:

>     > -d21.12

the output that is produced when the same rule-set number and address are entered is more verbose than it was before:

>     >  0 george
>     rewrite: ruleset   0   input: george
>     ---trying rule: @
>     --- rule fails
>     ---trying rule: $* < @ $+ > $*
>     --- rule fails
>     ---trying rule: $+
>     ---rule matches: $# local $: $1
>     rewritten as: $# local $: george
>     rewrite: ruleset   0 returns: $# local $: george

Observe that the first rule in rule set 0 (the lone `@`) does not match `george` in the workspace. Therefore that rule `fails` and is skipped. Then the more complicated rule (`$*<@$+>$*`) is tried, and it too fails. Finally, the `$+` operator in the last rule matches `george`, and the workspace is rewritten.

Note that the extra output that is produced by `-d` can potentially run to many lines. To capture the output for later examination, consider running sendmail in rule-testing mode from within a script(1), emacs(1), or similar session.

Higher levels of debugging are also available for examining rules and rule sets. The level `-d21.15` shows `$``digit` operators on the RHS being substituted with values from the LHS. The level `-d21.35` causes each comparison, token versus token, to be printed.

To turn off the extra debugging output, just reuse the `-d` rule-testing command and specify a level of zero:

>     > -d21.0

A `-d` with no category or level behaves the same as the `-d` command-line switch (see Section 37.1, "The Syntax of -d"). It sets a default of `0-99.1`.

### 38.7.1 A Trick

In debugging large configuration files, the output that is produced by the `-d21.15` switch can become too huge to examine conveniently. A good alternative (when modifying or adding rules) is to temporarily insert a fake subroutine call before and after individual rules to see what they do:

>     R$*      $:$>TEST $1        fake subroutine call
>     Rlhs     rhs                new rule
>     R$*      $:$>TEST $1        fake subroutine call

With the fake wrapper around the new rule (the name `TEST` is arbitrary), ordinary rule testing with `-bt` now shows how the address is rewritten by that rule:

>     rewrite: ruleset  3   input: ...
>     rewrite: ruleset TEST   input: ...
>     rewrite: ruleset TEST returns: ...
>                                        new rule acted here
>     rewrite: ruleset TEST   input: ...
>     rewrite: ruleset TEST returns: ...
>     rewrite: ruleset  3 returns: ...
>     >

If you use this technique, remember, of course, to remove the fake subroutine calls before putting that configuration file into use.

38.6 Process-Specified Addresses |  | 38.8 Batch Rule-Set Testing